home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpproceduraldb.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  18.9 KB  |  396 lines
  1. <refentry id="libgimp-gimpproceduraldb" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimpproceduraldb</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimpproceduraldb</refname><refpurpose></refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-proc-info">gimp_procedural_db_proc_info</link>    (<link linkend="gchar">gchar</link> *procedure,
  18.                                              <link linkend="gchar">gchar</link> **blurb,
  19.                                              <link linkend="gchar">gchar</link> **help,
  20.                                              <link linkend="gchar">gchar</link> **author,
  21.                                              <link linkend="gchar">gchar</link> **copyright,
  22.                                              <link linkend="gchar">gchar</link> **date,
  23.                                              <link linkend="GimpPDBProcType">GimpPDBProcType</link> *proc_type,
  24.                                              <link linkend="gint">gint</link> *num_args,
  25.                                              <link linkend="gint">gint</link> *num_values,
  26.                                              <link linkend="GimpParamDef">GimpParamDef</link> **args,
  27.                                              <link linkend="GimpParamDef">GimpParamDef</link> **return_vals);
  28. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-get-data">gimp_procedural_db_get_data</link>     (<link linkend="gchar">gchar</link> *identifier,
  29.                                              <link linkend="gpointer">gpointer</link> data);
  30. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-set-data">gimp_procedural_db_set_data</link>     (<link linkend="gchar">gchar</link> *identifier,
  31.                                              <link linkend="gpointer">gpointer</link> data,
  32.                                              <link linkend="guint32">guint32</link> bytes);
  33. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-dump">gimp_procedural_db_dump</link>         (<link linkend="gchar">gchar</link> *filename);
  34. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-query">gimp_procedural_db_query</link>        (<link linkend="gchar">gchar</link> *name,
  35.                                              <link linkend="gchar">gchar</link> *blurb,
  36.                                              <link linkend="gchar">gchar</link> *help,
  37.                                              <link linkend="gchar">gchar</link> *author,
  38.                                              <link linkend="gchar">gchar</link> *copyright,
  39.                                              <link linkend="gchar">gchar</link> *date,
  40.                                              <link linkend="gchar">gchar</link> *proc_type,
  41.                                              <link linkend="gint">gint</link> *num_matches,
  42.                                              <link linkend="gchar">gchar</link> ***procedure_names);
  43. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-proc-arg">gimp_procedural_db_proc_arg</link>     (<link linkend="gchar">gchar</link> *procedure,
  44.                                              <link linkend="gint">gint</link> arg_num,
  45.                                              <link linkend="GimpPDBArgType">GimpPDBArgType</link> *arg_type,
  46.                                              <link linkend="gchar">gchar</link> **arg_name,
  47.                                              <link linkend="gchar">gchar</link> **arg_desc);
  48. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-procedural-db-proc-val">gimp_procedural_db_proc_val</link>     (<link linkend="gchar">gchar</link> *procedure,
  49.                                              <link linkend="gint">gint</link> val_num,
  50.                                              <link linkend="GimpPDBArgType">GimpPDBArgType</link> *val_type,
  51.                                              <link linkend="gchar">gchar</link> **val_name,
  52.                                              <link linkend="gchar">gchar</link> **val_desc);
  53. <link linkend="gint">gint</link>        <link linkend="gimp-procedural-db-get-data-size">gimp_procedural_db_get_data_size</link>
  54.                                             (<link linkend="gchar">gchar</link> *identifier);
  55. </synopsis>
  56. </refsynopsisdiv>
  57.  
  58.  
  59.  
  60.  
  61.  
  62. <refsect1>
  63. <title>Description</title>
  64. <para>
  65.  
  66. </para>
  67. </refsect1>
  68.  
  69. <refsect1>
  70. <title>Details</title>
  71. <refsect2>
  72. <title><anchor id="gimp-procedural-db-proc-info">gimp_procedural_db_proc_info ()</title>
  73. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_proc_info    (<link linkend="gchar">gchar</link> *procedure,
  74.                                              <link linkend="gchar">gchar</link> **blurb,
  75.                                              <link linkend="gchar">gchar</link> **help,
  76.                                              <link linkend="gchar">gchar</link> **author,
  77.                                              <link linkend="gchar">gchar</link> **copyright,
  78.                                              <link linkend="gchar">gchar</link> **date,
  79.                                              <link linkend="GimpPDBProcType">GimpPDBProcType</link> *proc_type,
  80.                                              <link linkend="gint">gint</link> *num_args,
  81.                                              <link linkend="gint">gint</link> *num_values,
  82.                                              <link linkend="GimpParamDef">GimpParamDef</link> **args,
  83.                                              <link linkend="GimpParamDef">GimpParamDef</link> **return_vals);</programlisting>
  84. <para>
  85. Queries the procedural database for information on the specified
  86. procedure.
  87. </para>
  88. <para>
  89. This procedure returns information on the specified procedure. A
  90. short blurb, detailed help, author(s), copyright information,
  91. procedure type, number of input, and number of return values are 
  92. returned. Additionally this function returns specific information 
  93. about each input argument and return value.</para>
  94. <para>
  95.  
  96. </para><informaltable pgwide=1 frame="none" role="params">
  97. <tgroup cols="2">
  98. <colspec colwidth="2*">
  99. <colspec colwidth="8*">
  100. <tbody>
  101. <row><entry align="right"><parameter>procedure</parameter> :</entry>
  102. <entry> The procedure name.
  103. </entry></row>
  104. <row><entry align="right"><parameter>blurb</parameter> :</entry>
  105. <entry> A short blurb.
  106. </entry></row>
  107. <row><entry align="right"><parameter>help</parameter> :</entry>
  108. <entry> Detailed procedure help.
  109. </entry></row>
  110. <row><entry align="right"><parameter>author</parameter> :</entry>
  111. <entry> Author(s) of the procedure.
  112. </entry></row>
  113. <row><entry align="right"><parameter>copyright</parameter> :</entry>
  114. <entry> The copyright.
  115. </entry></row>
  116. <row><entry align="right"><parameter>date</parameter> :</entry>
  117. <entry> Copyright date.
  118. </entry></row>
  119. <row><entry align="right"><parameter>proc_type</parameter> :</entry>
  120. <entry> The procedure type.
  121. </entry></row>
  122. <row><entry align="right"><parameter>num_args</parameter> :</entry>
  123. <entry> The number of input arguments.
  124. </entry></row>
  125. <row><entry align="right"><parameter>num_values</parameter> :</entry>
  126. <entry> The number of return values.
  127. </entry></row>
  128. <row><entry align="right"><parameter>args</parameter> :</entry>
  129. <entry> The input arguments.
  130. </entry></row>
  131. <row><entry align="right"><parameter>return_vals</parameter> :</entry>
  132. <entry> The return values.
  133. </entry></row>
  134. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  135. </entry></row>
  136. </tbody></tgroup></informaltable></refsect2>
  137. <refsect2>
  138. <title><anchor id="gimp-procedural-db-get-data">gimp_procedural_db_get_data ()</title>
  139. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_get_data     (<link linkend="gchar">gchar</link> *identifier,
  140.                                              <link linkend="gpointer">gpointer</link> data);</programlisting>
  141. <para>
  142. Returns data associated with the specified identifier.
  143. </para>
  144. <para>
  145. This procedure returns any data which may have been associated with
  146. the specified identifier. The data is copied into the given memory 
  147. location.</para>
  148. <para>
  149.  
  150. </para><informaltable pgwide=1 frame="none" role="params">
  151. <tgroup cols="2">
  152. <colspec colwidth="2*">
  153. <colspec colwidth="8*">
  154. <tbody>
  155. <row><entry align="right"><parameter>identifier</parameter> :</entry>
  156. <entry> The identifier associated with data.
  157. </entry></row>
  158. <row><entry align="right"><parameter>data</parameter> :</entry>
  159. <entry> A byte array containing data.
  160. </entry></row>
  161. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success, FALSE if no data has been associated with 
  162. the identifier
  163. </entry></row>
  164. </tbody></tgroup></informaltable></refsect2>
  165. <refsect2>
  166. <title><anchor id="gimp-procedural-db-set-data">gimp_procedural_db_set_data ()</title>
  167. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_set_data     (<link linkend="gchar">gchar</link> *identifier,
  168.                                              <link linkend="gpointer">gpointer</link> data,
  169.                                              <link linkend="guint32">guint32</link> bytes);</programlisting>
  170. <para>
  171. Associates the specified identifier with the supplied data.
  172. </para>
  173. <para>
  174. This procedure associates the supplied data with the provided
  175. identifier. The data may be subsequently retrieved by a call to
  176. 'procedural-db-get-data'.</para>
  177. <para>
  178.  
  179. </para><informaltable pgwide=1 frame="none" role="params">
  180. <tgroup cols="2">
  181. <colspec colwidth="2*">
  182. <colspec colwidth="8*">
  183. <tbody>
  184. <row><entry align="right"><parameter>identifier</parameter> :</entry>
  185. <entry> The identifier associated with data.
  186. </entry></row>
  187. <row><entry align="right"><parameter>data</parameter> :</entry>
  188. <entry> A byte array containing data.
  189. </entry></row>
  190. <row><entry align="right"><parameter>bytes</parameter> :</entry>
  191. <entry> The number of bytes in the data
  192. </entry></row>
  193. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  194. </entry></row>
  195. </tbody></tgroup></informaltable></refsect2>
  196. <refsect2>
  197. <title><anchor id="gimp-procedural-db-dump">gimp_procedural_db_dump ()</title>
  198. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_dump         (<link linkend="gchar">gchar</link> *filename);</programlisting>
  199. <para>
  200. Dumps the current contents of the procedural database
  201. </para>
  202. <para>
  203. This procedure dumps the contents of the procedural database to the
  204. specified file. The file will contain all of the information
  205. provided for each registered procedure. This file is in a format
  206. appropriate for use with the supplied \"pdb_self_doc.el\" Elisp
  207. script, which generates a texinfo document.</para>
  208. <para>
  209.  
  210. </para><informaltable pgwide=1 frame="none" role="params">
  211. <tgroup cols="2">
  212. <colspec colwidth="2*">
  213. <colspec colwidth="8*">
  214. <tbody>
  215. <row><entry align="right"><parameter>filename</parameter> :</entry>
  216. <entry> The dump filename.
  217. </entry></row>
  218. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  219. </entry></row>
  220. </tbody></tgroup></informaltable></refsect2>
  221. <refsect2>
  222. <title><anchor id="gimp-procedural-db-query">gimp_procedural_db_query ()</title>
  223. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_query        (<link linkend="gchar">gchar</link> *name,
  224.                                              <link linkend="gchar">gchar</link> *blurb,
  225.                                              <link linkend="gchar">gchar</link> *help,
  226.                                              <link linkend="gchar">gchar</link> *author,
  227.                                              <link linkend="gchar">gchar</link> *copyright,
  228.                                              <link linkend="gchar">gchar</link> *date,
  229.                                              <link linkend="gchar">gchar</link> *proc_type,
  230.                                              <link linkend="gint">gint</link> *num_matches,
  231.                                              <link linkend="gchar">gchar</link> ***procedure_names);</programlisting>
  232. <para>
  233. Queries the procedural database for its contents using regular
  234. expression matching.
  235. </para>
  236. <para>
  237. This procedure queries the contents of the procedural database. It
  238. is supplied with seven arguments matching procedures on { name,
  239. blurb, help, author, copyright, date, procedure type}. This is
  240. accomplished using regular expression matching. For instance, to
  241. find all procedures with \"jpeg\" listed in the blurb, all seven
  242. arguments can be supplied as \".*\", except for the second, which
  243. can be supplied as \".*jpeg.*\". There are two return arguments for
  244. this procedure. The first is the number of procedures matching the
  245. query. The second is a concatenated list of procedure names
  246. corresponding to those matching the query. If no matching entries
  247. are found, then the returned string is NULL and the number of
  248. entries is 0.</para>
  249. <para>
  250.  
  251. </para><informaltable pgwide=1 frame="none" role="params">
  252. <tgroup cols="2">
  253. <colspec colwidth="2*">
  254. <colspec colwidth="8*">
  255. <tbody>
  256. <row><entry align="right"><parameter>name</parameter> :</entry>
  257. <entry> The regex for procedure name.
  258. </entry></row>
  259. <row><entry align="right"><parameter>blurb</parameter> :</entry>
  260. <entry> The regex for procedure blurb.
  261. </entry></row>
  262. <row><entry align="right"><parameter>help</parameter> :</entry>
  263. <entry> The regex for procedure help.
  264. </entry></row>
  265. <row><entry align="right"><parameter>author</parameter> :</entry>
  266. <entry> The regex for procedure author.
  267. </entry></row>
  268. <row><entry align="right"><parameter>copyright</parameter> :</entry>
  269. <entry> The regex for procedure copyright.
  270. </entry></row>
  271. <row><entry align="right"><parameter>date</parameter> :</entry>
  272. <entry> The regex for procedure date.
  273. </entry></row>
  274. <row><entry align="right"><parameter>proc_type</parameter> :</entry>
  275. <entry> The regex for procedure type: { 'Internal GIMP procedure', 'GIMP Plug-in', 'GIMP Extension' }.
  276. </entry></row>
  277. <row><entry align="right"><parameter>num_matches</parameter> :</entry>
  278. <entry> The number of matching procedures.
  279. </entry></row>
  280. <row><entry align="right"><parameter>procedure_names</parameter> :</entry>
  281. <entry> The list of procedure names.
  282. </entry></row>
  283. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  284. </entry></row>
  285. </tbody></tgroup></informaltable></refsect2>
  286. <refsect2>
  287. <title><anchor id="gimp-procedural-db-proc-arg">gimp_procedural_db_proc_arg ()</title>
  288. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_proc_arg     (<link linkend="gchar">gchar</link> *procedure,
  289.                                              <link linkend="gint">gint</link> arg_num,
  290.                                              <link linkend="GimpPDBArgType">GimpPDBArgType</link> *arg_type,
  291.                                              <link linkend="gchar">gchar</link> **arg_name,
  292.                                              <link linkend="gchar">gchar</link> **arg_desc);</programlisting>
  293. <para>
  294. Queries the procedural database for information on the specified
  295. procedure's argument.
  296. </para>
  297. <para>
  298. This procedure returns information on the specified procedure's
  299. argument. The argument type, name, and a description are retrieved.</para>
  300. <para>
  301.  
  302. </para><informaltable pgwide=1 frame="none" role="params">
  303. <tgroup cols="2">
  304. <colspec colwidth="2*">
  305. <colspec colwidth="8*">
  306. <tbody>
  307. <row><entry align="right"><parameter>procedure</parameter> :</entry>
  308. <entry> The procedure name.
  309. </entry></row>
  310. <row><entry align="right"><parameter>arg_num</parameter> :</entry>
  311. <entry> The argument number.
  312. </entry></row>
  313. <row><entry align="right"><parameter>arg_type</parameter> :</entry>
  314. <entry> The type of argument.
  315. </entry></row>
  316. <row><entry align="right"><parameter>arg_name</parameter> :</entry>
  317. <entry> The name of the argument.
  318. </entry></row>
  319. <row><entry align="right"><parameter>arg_desc</parameter> :</entry>
  320. <entry> A description of the argument.
  321. </entry></row>
  322. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  323. </entry></row>
  324. </tbody></tgroup></informaltable></refsect2>
  325. <refsect2>
  326. <title><anchor id="gimp-procedural-db-proc-val">gimp_procedural_db_proc_val ()</title>
  327. <programlisting><link linkend="gboolean">gboolean</link>    gimp_procedural_db_proc_val     (<link linkend="gchar">gchar</link> *procedure,
  328.                                              <link linkend="gint">gint</link> val_num,
  329.                                              <link linkend="GimpPDBArgType">GimpPDBArgType</link> *val_type,
  330.                                              <link linkend="gchar">gchar</link> **val_name,
  331.                                              <link linkend="gchar">gchar</link> **val_desc);</programlisting>
  332. <para>
  333. Queries the procedural database for information on the specified
  334. procedure's return value.
  335. </para>
  336. <para>
  337. This procedure returns information on the specified procedure's
  338. return value. The return value type, name, and a description are
  339. retrieved.</para>
  340. <para>
  341.  
  342. </para><informaltable pgwide=1 frame="none" role="params">
  343. <tgroup cols="2">
  344. <colspec colwidth="2*">
  345. <colspec colwidth="8*">
  346. <tbody>
  347. <row><entry align="right"><parameter>procedure</parameter> :</entry>
  348. <entry> The procedure name.
  349. </entry></row>
  350. <row><entry align="right"><parameter>val_num</parameter> :</entry>
  351. <entry> The return value number.
  352. </entry></row>
  353. <row><entry align="right"><parameter>val_type</parameter> :</entry>
  354. <entry> The type of return value.
  355. </entry></row>
  356. <row><entry align="right"><parameter>val_name</parameter> :</entry>
  357. <entry> The name of the return value.
  358. </entry></row>
  359. <row><entry align="right"><parameter>val_desc</parameter> :</entry>
  360. <entry> A description of the return value.
  361. </entry></row>
  362. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  363. </entry></row>
  364. </tbody></tgroup></informaltable></refsect2>
  365. <refsect2>
  366. <title><anchor id="gimp-procedural-db-get-data-size">gimp_procedural_db_get_data_size ()</title>
  367. <programlisting><link linkend="gint">gint</link>        gimp_procedural_db_get_data_size
  368.                                             (<link linkend="gchar">gchar</link> *identifier);</programlisting>
  369. <para>
  370. Returns size of data associated with the specified identifier.
  371. </para>
  372. <para>
  373. This procedure returns the size of any data which may have been
  374. associated with the specified identifier. If no data has been
  375. associated with the identifier, an error is returned.</para>
  376. <para>
  377.  
  378. </para><informaltable pgwide=1 frame="none" role="params">
  379. <tgroup cols="2">
  380. <colspec colwidth="2*">
  381. <colspec colwidth="8*">
  382. <tbody>
  383. <row><entry align="right"><parameter>identifier</parameter> :</entry>
  384. <entry> The identifier associated with data.
  385. </entry></row>
  386. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The number of bytes in the data.
  387. </entry></row>
  388. </tbody></tgroup></informaltable></refsect2>
  389.  
  390. </refsect1>
  391.  
  392.  
  393.  
  394.  
  395. </refentry>
  396.